/******************************************************************************
 * @file     bsp_led_handler.h
 * @brief    led handler层
 * @author   Ruilist
 * @date     2025-08-26
 * @version  V1.0.0
 * @copyright Copyright (c) 2025
 *
 * @note     1 tab = 4 space
 *           依赖 <stdio.h>
 *           依赖 <stdint.h>
 *           依赖 bsp_led_driver.h
 *
 * @par 日志:
 * - V1.0.0 2025-08-26 Ruilist
 *****************************************************************************/
#ifndef __BSP_LED_HANDLER_H__
#define __BSP_LED_HANDLER_H__

//******************************** Includes *********************************//

#include <stdio.h>
#include <stdint.h>
#include "bsp_led_driver.h"

//******************************** Includes *********************************//

//******************************** Defines **********************************//

#define OS_SUPPORTING  // 支持OS操作系统
#define DEBUG          // 开启DEBUG模式

#ifdef DEBUG
#define DEBUG_OUT( X ) printf( X ) /*DEBUG调试信息输出接口*/
#endif                             // DEBUG

/**
 * @brief LED句柄初始化状态枚举
 */
typedef enum
{
    HANDLER_NOT_INITED = 0,  // LED句柄未初始化
    HANDLER_INITED     = 1   // LED句柄已初始化
} led_handler_init_t;

/**
 * @brief LED索引枚举
 */
typedef enum
{
    LED_1 = 0,                  // LED索引1
    LED_2,                      // LED索引2
    LED_3,                      // LED索引3
    LED_4,                      // LED索引4
    LED_5,                      // LED索引5
    LED_6,                      // LED索引6
    LED_7,                      // LED索引7
    LED_8,                      // LED索引8
    LED_9,                      // LED索引9
    LED_10,                     // LED索引10
    MAX_INSTANCE_NUMBER,        // 系统支持的最大LED实例数量
    LED_NOT_INITIALIZED = 0xFF  // 表示LED未初始化的特殊标识
} led_index_t;

/**
 * @brief LED句柄操作状态枚举
 */
typedef enum
{
    HANDLER_OK              = 0,     // 表示LED操作成功
    HANDLER_ERROR           = 1,     // 表示LED操作中出现了一般错误
    HANDLER_ERROR_TIMEOUT   = 2,     // 表示LED操作超时
    HANDLER_ERROR_RESOURCES = 3,     // 表示资源不足，无法完成LED操作
    HANDLER_ERROR_PARAMETER = 4,     // 表示传入的参数无效
    HANDLER_ERROR_NOMEMORY  = 5,     // 表示内存不足，无法完成LED操作
    HANDLER_ERROR_ISR       = 6,     // 表示ISR（中断服务例程）中发生了错误
    HANDLER_ERROR_BUSY      = 7,     // 表示LED忙，无法执行操作
    HANDLER_ERROR_RESERVED  = 0XFF,  // 保留的错误码，用于未来扩展
} led_handler_status_t;

/**
 * @brief 时基函数指针结构体
 */
typedef struct
{
    led_handler_status_t ( *pf_get_time )( uint32_t *const );  // 获得时基函数
} handler_time_base_t;

#ifdef OS_SUPPORTING

/**
 * @brief OS延时函数指针结构体
 */
typedef struct
{
    led_handler_status_t ( *pf_os_delay )( const uint32_t );  // 获得OS延时函数
} handler_os_delay_t;

/**
 * @brief LED句柄相关的OS队列操作函数指针结构体
 */
typedef struct
{
    // OS创建队列函数
    led_handler_status_t ( *pf_os_queue_create )( uint32_t const item_num,
                                                  uint32_t const item_size,
                                                  void **const   queue_handler );

    // OS队列发送函数
    led_handler_status_t ( *pf_os_queue_put )( void *const queue_handler,
                                               void *const item,
                                               uint32_t    timeout );

    // OS队列接收函数
    led_handler_status_t ( *pf_os_queue_get )( void *const queue_handler,
                                               void *const msg,
                                               uint32_t    timeout );
    // OS队列删除函数
    led_handler_status_t ( *pf_os_queue_delete )( void *const queue_handler );
} handler_os_queue_t;

/**
 * @brief LED句柄相关的OS临界区函数指针结构体
 */
typedef struct
{
    led_handler_status_t ( *pf_os_critical_enter )( void );  // 进入临界区
    led_handler_status_t ( *pf_os_critical_exit )( void );   // 退出临界区
} handler_os_critical_t;

/**
 * @brief LED句柄相关的OS线程函数指针结构体
 */
typedef struct
{
    // OS创建线程函数
    led_handler_status_t ( *pf_os_thread_create )(
        void *const       task_code,
        const char *const task_name,
        const uint32_t    stack_depth,
        void *const       parameters,
        uint32_t          priority,
        void **const      task_handler );

    // OS删除线程函数
    led_handler_status_t ( *pf_os_thread_delete )( void * ); /* Thread delete   */

} handler_os_thread_t;

#endif  // OS_SUPPORTING

typedef struct bsp_led_handler bsp_led_handler_t;

/**
 * @brief LED句柄控制函数指针类型定义
 */
typedef led_handler_status_t ( *pf_handler_led_control )(
    bsp_led_handler_t *const,  // LED句柄
    uint32_t,                  // 闪烁周期(ms)
    uint32_t,                  // 闪烁次数
    led_duty_cycle_t,          // 闪烁占空比
    led_index_t const          // LED句柄中LED实例索引
);

/**
 * @brief LED句柄注册LED实例函数指针类型定义
 */
typedef led_handler_status_t ( *pf_handler_led_register )(
    bsp_led_handler_t *const,  // LED句柄
    bsp_led_driver_t *const,   // LED实例
    led_index_t *const index   // LED句柄中LED实例索引
);

/**
 * @brief LED实例注册管理结构体
 */
typedef struct
{
    uint32_t          led_instance_num;  // 当前已注册的LED实例数量
    bsp_led_driver_t *led_instance_group[MAX_INSTANCE_NUMBER];
    // LED实例指针数组，存储所有已注册的LED驱动实例指针
} instance_registered_t;

/**
 * @brief BSP层LED句柄结构体
 */
typedef struct bsp_led_handler
{
    led_handler_init_t   init_status;
    handler_time_base_t *p_time_base;

    void *queue_handler;
    void *thread_handler;

#ifdef OS_SUPPORTING
    handler_os_delay_t    *p_os_time_delay;
    handler_os_queue_t    *p_os_queue;
    handler_os_critical_t *p_os_critical;
    handler_os_thread_t   *p_os_thread;
#endif  // OS_SUPPORTING
    pf_handler_led_control  pf_led_countroler;
    pf_handler_led_register pf_led_register;
    instance_registered_t   instances;

} bsp_led_handler_t;

//******************************** Declaring ********************************//

/**
 * @brief   LED句柄挂载函数
 *
 * @param   bsp_led_handler_t *const self            led句柄结构体指针
 * @param   os_delay_t *const os_delay               OS延时函数指针
 * @param   handler_os_queue_t *const os_queue       OS队列操作函数结构体指针
 * @param   handler_os_critical_t *const os_critical OS临界区操作函数结构体指针
 * @param   handler_os_thread_t *const os_thread     OS线程操作函数结构体指针
 * @param   handler_time_base_ms_t *const time_base  时基函数指针
 *
 * @return  led_handler_status_t 函数运行状态
 *
 * @retval  HANDLER_OK                操作成功
 * @retval  HANDLER_ERROR_PARAMETER   传入参数错误
 */
led_handler_status_t led_handler_inst(
    bsp_led_handler_t *const self,
#ifdef OS_SUPPORTING
    handler_os_delay_t *const    os_delay,
    handler_os_queue_t *const    os_queue,
    handler_os_critical_t *const os_critical,
    handler_os_thread_t *const   os_thread,
#endif  // OS_SUPPORTING
    handler_time_base_t *const time_base );

//******************************** Declaring ********************************//

#endif  // End of __BSP_LED_HANDLER_H__
